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This  paper  reviews  state  of  the  art  for  high  level 
programming  languap.es  and  traces  their  development  from 
first  generation  computers  to  the  presont  day.  A review 
and  comparison  of  industry  and  Army  standards  for  program 
documentation  is  made  and  differences  discussed.  Based 
upon  field  interviews,  findings  concerning  command  unique 
documentation  are  presented.  Conclusions  Indicate  that 
more  powerful  and  cost  effective  high  level  languages  are 
available  for  use  and  that  documentation  for  command 
unique  software  is  not  adequate.  Ifecommondations  are  made 
for  securing  a system  language,  establishing  a central 
review  and  approval  authority  for  software  documentation, 
and  for  various  follow  up  studios. 


The  purpose  of  this  review  is  to  evaluate 
"high  level"  programming  lnnguu.  os  used  within  the 
Amy  ami  to  determine  if  state  or'  the  art  capability 
ia  being  exploited,  in  addition,  a review  of 
existing  software  documentation  standards  will  he 
conducted  in  order  to  determine  adequacy  . 

Although  numerous  high  level  pro. ramming 
lan  -.ua  ,es  oxist  within  the  Apr  community,  the  U.  b. 

Army  currently  limit:-  Ah:'  languages  to  three: 

FORTRAN,  COBOL,  and  AhiC.  (Exceptions  exist  for 
limited  purposes.)  These  languages  are  in  use  due 
to  historic  situations  and  may  or  may  not  present 
limitations  to  pro.  rammin.  capability.  Closely  related 
to  program  languages  is  pro-Tam  documentation,  with 
some  lan  .ua  .es  being,  more  self  documenting,  than 
others.  Lorn,  term  benefits  can  be  expected  when 
documentation  is  properly  accomplished.  Improper 
documentation  can  lead  to  excessive  costs-  when 
specific  programmers  change  employment,  when  new 
hardware  is  purchased  or  when  attempts  are  made  to 
export  the  system. 

In  order  to  narrow  the  scope  of  the  review, 
and  to  keep  it  within  manageable  bounds,  only 
command  unique  software  will  be  addressed.  This 
limitation  also  recognises  the  fact,  that  ropurtment 
of  the  Army  standard  systems  are  deve  loped  by  or- ani- 
mations with  greater  resources  and  capabilities  than 
local  data  processing,  institutions. 

Methodology  for  conducting,  this  study- 
consisted  of  a review  of  applicable  ’department 
of  Defense  instructions , Department  of  the  Army- 
Regulations , U.  b . Army  Computer  Systems  Command 
Technical  Manuals,  academic  literature  and  personal 
interviews  with  military  and  civilian  programmers 
and  managers . 


Department  of  Defense  instructions,  Department 
of  the  Army  Regulations,  and  U.  F.  Army  Computer 
Systems  Command  Technical  Manuals  were  used  to 
establish  familiarity  with  existing  standards  and 
to  provide  a base  for  comparison,  likewise, 
academic  literature  was  vised  to  gain  knowled,  e of 
standards  accepted  by  the  teaching  profession.  The 
personal  interviews  allowed  n determination  of 
"in  fact"  situations  and  comparisons  against 
standards  to  be  made.  In  the  interest  of  accurate 
information,  those  interviewed  were  given  assurances 
of  non-attribution.  Locations  selected  for  obtaining 
interviews  wore  wide  spread  and  diverse.  In  all, 
thirty  programmers  from  two  divisions,  one  Corps, 
headquarters,  an  Army  headquarters  and  two  installa- 
tions were  interviewed.  In  addition,  management 
personnel  from  Department  of  the  Amy,  l . b . Army 
Computer  Systems  Command  and  the  Army  and  Air  Force 
Exchange  System  were  contacted. 

Interviews  and  discussions  wore  based  upon  the 
fol 1 owing  questions : 

1.  In  what  way  did  you  learn  to  prog. ram? 

2.  What  is  your  experience  level? 

3.  In  what  programming  languages  are  you 
qualified? 

4.  When  programming,  how  do  you  select  variable 
names  to  be  used? 

5.  When  programming,  how  do  you  determine 
the  composition  of  a data  element. 


'.ho  is  responsible  for  software  documenta- 


tion? 


7.  Does  your  software  documentation  contain 
a pro,  ram  narrative,  comments  throughout  the  prog. ram, 
and  a prog. ram  flowchart? 

a.  Who  approves  your  finished  documentation? 


9.  In  your  opinion,  and  based  upon  your 
experience,  have  your  supervisors  been  technically 
capable  of  reviewing  your  work? 

10.  \,'hen  programming,  what  reference  docu- 
ments do  you  use  to  assist  you  should  you  have 
problems? 

11.  Do  you  program  for  hardware  independence? 

12.  Has  any  outside  agency  ever  checked  your 
completed  work? 

13.  How  do  you  account  for  time  spent  programming? 

14.  Arc  you  given  a restriction  as  to  the 
maximum  allowable  core  size  which  you  may  use? 

15.  When  programming,  do  you  use  subroutines? 

If  so,  how? 

lb.  Do  you  have  any  comments  concerning 
program  languages  or  documentation  which  you  would 
like  to  make? 

Certain  data  processing  terms,  which  are 
important  for  accurate  understanding,  are  used 
throughout  the  text  of  this  report.  Definitions 
are  therefore  provided  below.  Unless  otherwise 
stated,  definitions  are  from  IBM's  "Data  Processing 
Glossary" . 

ANSI:  American  National  Standards  Institute.  An 

organization  sponsored  by  the  Business  Equipment 
Manufacturers  Association  (BEMA)  for  the  purpose 
of  establishing  voluntary  industry  standards. 

Abbreviated  ANSI. 

(assembler  language)  A source  language 
that  includes  symbolic  machine  language  statements 
in  which  there  is  a one-to-one  correspondence 
with  the  instruction  formats  and  data  formats  of 
the  computer. 

BABIC:  An  algebra-like  language  used  for  problem 

solving  by  engineers,  scientists  and  others  who 


Assembl 


may  not  bo  profcr.  ional  ro>*  rammer  a , 

Character:  A letter,  di.  it,  or  other  symbol  that 
is  used  as  art  of  the  or  anization,  control,  or 
representation  of  data.  A character  5a  often  in 
the  for m of  a spatial  arrangement  of  adjacent  or 
connected  strokes. 

CObOL:  COmmon  business-Oriented  Language.  A 
business  data  processing  langua.  c. 

Command  Unique:  An  AhP  system  supporting  a functional 
application  unique  to  a single  Army  command,  installa- 
tion, or  activity.  (Author's  defination.) 

Comment:  (comment  statement)  A statement  used  to 

include  information  that  may  be  helpful  in  running 
a job  or  reviewin  an  output  listin  . 

Coro : (magnetic  core)  A configuration  of  magnetic 

material  that  is,  or  is  intended  to  be,  placed  in 
a spatial  relations))!;  to  current-carryin;  conductors 
and  whose  mn  netic  properties  are  essential  to 
its  use.  It  may  be  used  to  concentrate  an  induced 
rna  netic  field  as  in  a transformer  induction  coil, 
or  armature,  to  retain  a magnetic  polarization 
for  the  purpose  of  storin  data,  or  for  its  nonlinear 
properties  as  in  a logic  element*  It  may  be  made 
of  such  material  as  iron,  iron  oxide,  or  ferrite 
and  in  such  shapes  as  wires,  tapes,  toroids,  rods, 
or  thin  film, 

data  Element:  Grouping  of  information  units  which 
have  a unique  meaning  and  sub-categ.ories  (data  items) 
of  distinct  units  or  values.  Examples  of  data 
elements  are  military  personnel  ..rade,  sex,  race, 
geographic  location,  and  military  unit,  (Army 
Regulation  lo-l) 

Flowchart : A graphical  representation  for  the 

definition,  analysis,  or  solution  of  a problem,  in 


which  symbols  are  used  to  represent  operations, 
data,  flow,  equipment,  etc. 

FORTRAI! : FORmula  TRANslating  system.  A lan. qua  e 

primarily  used  to  express  computer  pro  -.rams  by 
arithmetic  formulas. 

Hardware : Physical  equipment,  as  opposed  to  the 

computer  pro p.ram  or  method  of  use,  for  example, 
mechanical,  magnetic,  electrical,  or  electronic 
devices . 

High  Level  Language:  A language  used  to  prepare 
computer  programs.  A set  of  representations,  conven 
tions,  and  rules  used  to  convey  information;  more 
like  human  language  than  machine  language.  A 
language  which  must  be  translated  into  machine 
language  prior  to  use  by  a computer. 

JOVIAL;  A hi.h  level  language  used  within  DOD  for 
programming  command  and  control  applications. 
(Author's  definition) 

Listin  , : (program  listing)  A printout,  usually 
prepared  by  a lan  ,ua  -.e  translator,  that  lists  the 
source  langua  ,e  statements  and  contents  of  a . ro  ram 
Overlay ; (1)  The  technique  of  repeatedly  usin 

the  same  blocks  of  internal  stora  e during  different 
stages  of  a pro  ram.  When  one  routine  is  no 
longer  needed  in  storage,  another  routine  can 
replace  all  or  part  of  it.  (2)  A pro  ram  segment 
or  phase  that  is  loaded  into  main  storage.  It 
replaces  all  or  part  of  a • reviously  loaded  se.  nent. 
PL/ 1 ; A high-level  programming  language,  desi yned 
for  use  in  a wide  range  of  commercial  and  scientific 
computer  applications. 

Prog, ram  Narrative:  The  details  and  characteristics 
of  a program  or  subroutine  which  would  be  ox  value 
to  a maintenance  programmer  in  understanding  the 
program. 


RPC : Report  procram  generator. 

Software:  A set  of  programs,  procedures,  and  possibly 

associated  documentation  concerned  v/ith  the  operation 
of  a data  processing  system.  For  example,  compilers, 
library  routines,  manuals,  circuit  diagrams. 

Subroutine : A segment  of  coded  instructions  which 

can  be  stored  at  one  place  and  can  be  linked  to 
one  or  more  other  calling  routines. 

Variable  Name:  An  alphameric  term  that  identifies 
a data  set,  a control  statement,  a program,  or  a 
procedure. 

l/ord:  A sequence  of  bits  or  characters  treated  as 

a unit  and  capable  of  being  stored  in  one  computer 
location.  Synonymous  with  machine  word. 
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The  history  of  programming  Ian.: uar.es  parallels 
the  development  phases  as  the  computer  itself.  Original 
first  generation  computers  were  slow,  had  limited 
capacity  and  very  little  capability  for  control  or 
assistance  to  pro  rams  being  used.  The  programmer 
had  to  specify  in  exact  and  painstaking,  detail  each 
function  to  be  performed.  In  order  to  do  so,  the 
programmer  used  either  machine  or  assembly  langua  e. 

A thorough  knowledge  of  hardware  was  required  and 
programs  were  complex.  As  an  example,  consider  the 
steps  necessary  to  keep  track  of  an  exponent  without 
the  aid  of  floating,  point  arithmetic  now  so  commonly 
used. 

As  computer  capability  passed  into  the  second 
and  third  generation,  more  machine  assistance 
became  available.  The  programmer  no  longer  had  to 
pro  ram  in  an  abstract  form  which  might  read 
M333272P  (Move  contents  of  location  333  to  location 
272  and  punch  a card.).  Rather,  high  level  lanuagcs 
were  available.  High  level  languages  are  more 
En?  lish-likc  or  are  closely  related  to  mathmatical 
formulas.  The  programmer  does  not  have  to  keep 
track  of  finite  details  and  can  program  in  broader 
terms.  In  turn,  the  computer  uses  a software  routine 
called  a compiler  to  transform  high  level  lan  ,ua  er. 
into  machine  languages.  The  power  of  this  capabilty 
can  be  seen  in  the  fact  that  one  high  level  instruc- 
tion, after  being  compiled,  may  result  in  an  entire 
subroutine  of  machine  language  code.  First 
. .one ration  langua  .es  (assembly)  resulted  in  a one 
for  one  translation.  High  level  languag.es  also 
have  the  major  advantage  of  nllowin#  the  programmer 
to  think  in  a language  closely  related  to  normal 
problem  solving,.  Well  known  examples  are  COHOL 
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and  FORTRAN. 

A new  capability  is  being  seen  in  the  market 
place  today.  This  capability  is  high  level  language 
which  "designs"  a system  and  is  naturally  referred 
to  as  "system  language".  Just  as  a COBOL  statement 
generates  multiple  machine  language  instructions, 
system  language  instructions  generate  multiple 
COBOL  statements  which  then  generate  multiple 
machine  instructions.  As  one  example,  a system 
language  program  consisting  of  162  instructions 
generated  a COBOL  program  of  570  statements!  Not 
only  were  the  statements  generated,  but  they  were 
error  free.  Estimates-  also  indicate  that  75%  of  direct 
programming  time  can  be  saved  and  of  even  greater 
importance  is  the  fact  that  a system  language  gene- 
rates the  total  documentation  necessary  for  support- 
ing the  software. 

To  further  illustrate  the  capability  of  this 
type  of  high  level  language,  a detailed  description 
of  one  such  language  will  be  give.  Through  the 
courtesy  of  Thorne  Data  Processing,  Springfield, 
Virginia,  SL/l  is  described. 

"SL/1  is  a very  high-level  language.  As  its 
title  implies,  it  is  a systems  language.  It  is 
not  a programming  language,  but  rather  a systems 
language  used  to  specify  the  data  elements  for 
each  input  and  output  of  a system.  The  language 
is  very  powerful  and  permits  the  user  to  completely 
define  the  total  requirements  of  a system  in 
terms  of  elements  associated  with  inputs  and  out- 
puts. These  elements  may  be  input  elements  or 
generated  elements  for  which  the  user  must  provide 
the  element  formulas.  Full  arithmetic  and  condi- 
tional logic  may  be  used  in  specifing  the  element 


formulas.  The  system  elements  provide  the  basic 
in  rediont  for  the  building  block  approach  that  is 
used;  the  subordinate  elements  in  the  clement  for- 
mulas are  used  to  build  the  basic  elements,  the 
basic  elements  are  used  to  build  the  inputs  and 
outputs,  and  the  inputs  and  outputs  are  used  to 
build  the  system.  Since  SL/1  is  a data  and  element- 
formula  specification  language,  it  docs  not  contain 
the  verbs  and  operations  associated  with  conventional 
programmin.  languages,  i.e.,  READ  TO  CO,  etc.  The 
SL/1  user  is  never  concerned  with  such  programming 
details. 

During,  the  Requirements  Study  the  analyst 
used  the  SL/1  language  to  record  data  related  to 
each  data  input  (initial  inputs)  and  each  data 
output  (final  product)  of  the  proposed  system.  For 
inputs,  the  analyst  records  the  elements  (by  name) 
appearing  on  the  inputs  along  with  element  charac- 
teristics (size,  class,  number  of  decimals,  and 
whether  it  has  a sign).  Also,  information  related 
to  retention  (whether  or  not  the  element  should 
be  retained  in  a master  file)  of  the  elements  is 
recorded.  For  outputs,  the  element  names  desired 
on  each  output,  their  characteristics,  and  where 
they  print  (both  detail  print  information  and 
accumulated  totals)  is  recorded.  Report  title/ 
header  line  constants  and  total  line  identification 
constants  are  also  recorded.  The  formulas  of 
elements  to  be  generated  by  the  system  in  associa- 
tion with  either  inputs  or  outputs  are  > iven.  Only 
the  simple  element  name  relationships  usiiv  conditional 
and/or  arithmetic  logic  are  given. 

Programs  are  not  defined.  Master  and  work  files 
are  not  defined.  Only  the  system  inputs  and  outputs 
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are  defined.  While  SL/l  takes  care  of  the  design 
and  programming  details  automatically,  through  train- 
ing and  application  users  learn  how  SL/l  implicitly 
reacts  to  logical  system  specifications  and  are 
able  to  predict  or  force  resultant  physical  system 
configurations.  The  analyst  describes  a data  flow 
pattern  using  the  SL/l  language.  The  analyst  essen- 
tially states  at  a very  high  level  WHAT  is  to  be 
accomplished  and  SL/l  does  the  burdensome  detail  work. 
The  SL/l  language  statements  are  free  form.  Therefore, 
any  30  character  coding  sheet,  such  as  a COBOL  coding 
form,  may  be  used  to  record  the  statements." 

Documentation  provided  by  SL/l  includes: 
Input/Output  system  specifications 
Report  facsimilies 
Documentation  cover  page 
Table  of  contents 
System  description 
List  of  system  inputs 

Expanded  list  of  system  inputs  with  descriptions 
List  of  system  outputs 

Expanded  list  of  system  outputs  with  descriptions 

Master  file(s)  explanation 

Master  file(s)  general  information 

General  narrative  of  programs 

Detail  narrative  of  each  program 

Operation  of  system  narrative 

Production  control  sheet 

Tape  librarian  guide 

Key  punch  instructions 

System  flowchart 

Run  Book  (operating  documentation) 

JCL  cards 

Generation  data  set  control  JCL 
Program  input/output  record  layouts 


Element  to  reconi  layout  cross-reference 

Element  dictionary 

Element  edit  dictionary 

Element  edit  diagnostic  dictionary 

Master  file  rccord(s)  COUOL  specifications 

Code  Book  (for  elements  that  are  codes) 

Appendices 

Cource  program  listings 
Master  file  punch  outs 
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In  discussing  the  requirements  and  accepted 
principles  of  documentation,  a cleai'  distinction 
must  be  made  between  system  documentation  and  soft- 
ware documentation.  The  first,  and  most  obvious, 
distinction  beiny  that  software  documentation  is 
a sub-element  of  system  documentation.  Documentation 
for  an  ADD  system  includes  the  information  and 
instructions  necessary  for  overall  system  usage  and 
understanding.  As  software  is  a narrow  sub-set  of 
an  overall  system,  it  follows  that  software  (also 
referred  to  as  a program)  documentation  addresses 
a much  narrower  area.  The  Department  of  Defense 
describes  system  documentation  as  being  necessary 
in  order  to: 

"a.  Provide  managers  with  documents  to  review 
at  significant  developmental  mile- 
stones to  determine  that  requirements 
have  been  met  and  that  resources  should 
continue  to  be  expanded. 

Record  technical  information  to  allow 
coordination  of  later  development  and 
use/modification  of  the  ADS. 

Ensure  that  authors  of  documents  and 
managers  of  project  development  have  a 
guide  to  follow  in  preparing  and  checking 
documentation. 

rrov-rie  uniformity  of  format  and  content 

of  ADS  documentation  throughout  DOD 

2 

components. 

Industry  tends  to  narrow  it's  definition  of 
system  documentation  somewhat,  since  it  does  not 
have  to  worry  about  various  components  such  as 
those  found  within  the  Department  of  Defense.  One 
definition  of  system  documentation  applicable  to 
industry  (and  other  users  as  well)  reads: 


b. 


d. 


lb 


'•System  documentation  encompasses  all  informa- 


i 


tion  needed  to  define  the  proposed  data 
processing  system  to  a level  that  it  can  be 
programmed,  tested,  and  implemented.  The 
major  document  is  a system  specification 
which  acts  as  the  permanent  record  of  the 
structure,  functions,  flow,  and  control  of 
the  system.  It  is  the  basic  medium  of 
communication  of  information  about  the  pro- 
posed system  between  the  systems  design, 
programming,  and  user  functions.  System 

documentation  thus  specifies  how  a system 
3 

will  opei'ate."  Contrasting,  the  above  system 
documentation  reasoning  to  the  specifics  of 
software  documentation,  a summary  of  software 
documentation  can  be  expressed  as  "documentation 
comprises  the  records  of  the  detailed  logic  and 
coding  of  the  constituent  programs  of  a system."'' 

With  the  distinction  between  system  and  sol't- 
ware  documentation  in  mind,  a closer  look  at 
reasons  for  software  documentation  should  be  provided. 
Several  reasons  exist,  but  most  can  be  classed 
cither  directly  or  indirectly  into  the  broad  area 
of  maintenance.  Maintenance,  in  this  case,  being, 
simply  those  actions,  changes,  modifications  etc. 
necessary  to  keep  an  operational  software  program 
current  with  user  needs  or  operating  in  a changing, 
hardware  environment.  The  exception  to  this  class- 
ification is  documentation  necessary  to  aid  in 
pro  ram  development  and  acceptance.  The  considera- 
tion in  software  maintenance  therefore  is,  or 
should  be,  dollar  cost.  The  direct  relationship  bein 
a hi  ,h  cost  when  documentation  is  poor.  Whatever 
the  reason,  time  wasted  by  a programmer  or  analyst 
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translates  into  dollars 


Perhaps  the  most  basic  element  of  program 
maintenance  is  trout le  shootin.  . This  can  occur 
when  a system  is  placed  prematurely  into  an  opera- 
tional mode,  when  data  with  unplanned  aramenters 
becomes  the  norm,  or  when  a system  is  bein  field 
tested.  Another  maintenance  aspect  occurs  when 
hardware  is  chan  ed  or  converted,  as  different 
manufacturers  have  different  software  capabilities 
built  into  their  computers.  This  is  of  great  impor- 
tance in  the  military  community  as  competitive 
procurement  is  mandated.  Mobility  of  the  military 
member  also  directly  affects  software  maintenance. 
Seldom,  if  ever,  is  the  programmer's  availability 
the  same  as  the  life  cycle  of  the  software.  To 
the  extent  that  documentation  is  accurate,  another 
programmer  will  be  able  to  answer  questions  and  per- 
form maintenance  upon  the  program.  A ain,  poor 
documentation  results  in  later  unnecessar  costs. 
Unfortunately  these  costs  are  normally  tied  to 
"overhead"  or  "operating  costs"  and  are  not  attri- 
buted to  the  true  cause. 

Although  different  elements  of  industry  have 
different  software  documentation  standards,  most 
generally  follow  the  following  outline: 

1.  System  Flow  Chart:  shows  relation  of 
specific  program  to  entire  system. 

2.  System  Narrative:  similar  to  system 
flow  chart,  but  narrative  rather  than  visual. 

3.  Program  Flowchart:  visual  representation 
of  program  logic  and  structure. 

4.  Program  Narrative:  same  as  system 
narrative,  but  pertaininj  only  to  the  software. 

5.  Commented  Listing:  a listing  of  computer 
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program  instructions,  produced  by  the  computer, 
with  explanations  of  all  variables  and  methods. 

It  is  often  linked  to  specific  areas  of  a 
flow  chart  by  numbers. 

G.  File  and  Record  Description:  information 
describing  input  and  output  configuration. 

7.  Set-up  and  Run  Procedures:  information 
describing,  how  to  load  and  operate  the  software 
on  a computer.  Also  includes  instructions 

for  error  conditions. 

8.  Discussion  of  Valid  Data  Ranges:  an 
explanation  of  any  limits  existing  within  the 
program.  An  example  might  consist  of  a routine 
which  would  check  for  maximum  dollar  value  for 
an  order. 

9.  Discussion  of  Algorithms;  used  when 
complex  sorting,  formulas,  or  procedures  exist. 

The  composition  of  documentation  for  Army 

software  as  expressed  in  Army  Regulation  18-1, 
is:  Narrative  system  description,  system  description, 

system  flow  chart,  equipment  and  software  requirements, 
list  of  programs,  program  description,  program 
run  diagram,  input  device  document,  output  form 
layout  and  samples,  file  and  record  layouts,  detained 
program  narrative,  processing  macro-logic  chart, 
decision  tables,  timing  criteria,  operating 
instructions,  memory  layout,  detail  program 
flowchart,  program  logic  details,  miscellaneous 
information,  program  compilation  output,  test 
data  and  criteria  test  output  results,  and  test 
timing  results. 

Although  the  Army's  criteria  for  software 
documentation  appears  to  be  more  detailed,  a 
closer  examination  reveals  that  several  components 
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of  the  Army's  standards  are  in  fact  expressed  as 
one  industry  standard.  For  example,  the  Army's 
requirement  for:  equipment  and  software  require- 
ments, program  run  diagram,  input  device  document, 
output  form  layout,  timing  criteria,  operating 
instructions  and  miscellaneous  information  might  well 
be  components  of  industry's  Set-up  and  Run  Procedures. 
In  both  cases,  however,  the  intent  is  to  insure 
that  sufficient  information  is  provided. 

Tv/o  differences  exist  and  should  be  recognized. 
Industry's  requirement  for  comments  within  the 
program  listing  and  for  a discussion  of  Algorithms 
are  not  expressed  in  Army  requirements.  Without 
such  a stated  requirement,  complex  routines  may 
have  no  recorded  definition  of  logic  used  and 
program  listings  can  become  a maze  of  unknown 
variable  names  (also  called  data  items).  The 
Army's  principle  producer  of  large  software  systems. 
Computer  Systems  Command,  recognizes  the  importance 
of  this  area  and  offers  the  following  as  a guide 
but  not  as  a directive.  "Self  documenting  pro- 
grams aid  in  developing,  maintaining  and  reusing 
programs.  The  most  important  and,  unfortunately, 
the  most  neglected  program  documentation  is  the 
description  of  the  meaning  and  usage  of  data  items. 
How  often  have  we  questioned  why  a programmer 
redefines  an  alphanumeric  data  item  as  numeric? 

We  wonder  why  the  programmer  did  not  choose  one 
class  or  the  other;  so  we  go  tripping  through  the 
program  looking  for  the  answer.  The  easy  solution 
to  this  problem  is  to  provide  a brief  comment  by 
the  data  item  description." 

To  the  extent  that  standards  are  not  clearly 
stated  and,  most  importantly,  understood,  the 


unfortunate  programmer  and  supervisor  are  placed 
into  a position  of  asking:  What  do  I record?.  When 
do  I record  it?,  How  much  detail?,  and  How  will  it 
be  used?  For  the  Army,  one  other  important  question 
must  be  answered.  This  question,  "Who  approves  the 
program  documentation  and  determines  that  it  is 
sufficient?",  has  no  apparent  answer. 


A detailed  examination  and  discussion  of  data 
collected  liurin.t  interview;;  will  be  presented  on 
this  and  Col  low  in  pa. on.  Cone  lur.ionn  and  recomwon- 
dations  arc  stated  in  Chapter  V,  Iscussions  arc 
related  to  each  question  of  the  interview. 

Question  l.  "In  what  way  did  you  learn  to 
prop,  ran?  " 

The  purpose  of  thin  question  was  to  provide  a 
basin  for  evaluation  the  mix  of  instructional 
bias  existin  aiaon  those  bcin.  interviewed.  lor 
example,  if  a hi  h oroouta  o of  those  interviewed 
learned  in  a manufacturer  sponsored  environment, 
then  bias  toward  specific  tochni  uer-  and  standard;; 
would  exist.  ilesponsos  indicated  that  a bias  should 
not  ho  cx  ccted,  as  40  had  learned  in  various 
colic m's  and  civilian  institutions,  40  from  formal 
Army  trainin  , and  If  from  on  Job  trainin  within 
the  Army  or  from  self  tnu.ht  methods.  It  therefore 
appears  that  a valid  random  selection  of  persons, 
to  be  interviewed  was  made. 

Question  11 1. hat  ts  your  oxi'opl^noc  level?" 

This  question  was  used  to  nin  further  insight 
into  the  information  gathered  in  later  questions. 

A total  of  145  years  experience,  averaqinp  l.s  years 
per  pro  .rammer  war.  found.  Of  equal  importance, 
however,  is  the  fact  that  those  uv  rammers  have 
served  in  29  locations  world-wide.  It  can  therefore 
bo  reasonably  assumed  that  their  experiences  are 
representative  of  overall  conditions  throw,  houl 
the  Armj . 

Question  o.  "In  what,  programming  lan.  ua  os 
nrc  ;ou  qualified? " 

This  question  provides  ; 


i l)4sis  for  evaluatin 


comments  and  experiences  about  documentation,  as 
some  languages  are  more  self-documenting  than  others. 
Also,  knowledge  of  languages  provides  a basis  for 
discussing  existing  Army  standards.  Responses 
indicated  that  all  were  familiar  with  COBOL,  60% 
knew  FORTRAN,  4u,  could  program  in  ASSEMBLY,  26% 
in  BASIC  and  RPG,  20%  wore  capable  in  I’Ll  and  10% 
in  other  languages  such  as  PLC  and  JOVIAL.  Only 
26%  of  the  programmers  were  knowledgablo  in  only- 
one  language,  while  20%  could  use  two  languages, 

40%  were  capable  of  programming  in  more  than  three 
and  13%  had  the  capability  to  program  in  more  than 
five  languages . 

Ouestion  4.  "When  programming,  how  do  you  select 
variable  names?" 

Responses  to  this  question  indicate  the  degree 
to  which  standard  conventions  are  used.  Responses 
indicate  that  selection  was  entirely  up  to  the 
programmer.  All  programmers,  with  one  exception, 
indicated  that  the  same  basic  process  was  used — 
it  being  the  selection  of  "meaningful"  or  "logical" 
names.  The  obvious  problem  being  that  a name  which 
is  meaningful  or  logical  to  one  person  may  or  may 
not  be  to  another.  The  exception  mentioned  above 
indicated  that  he  used  "the  Computer  Systems  Command 
Naming  Convention  as  outlined  in  their  manuals" . 

Question  5.  "When  programming,  how  do  you 
determine  the  composition  of  a data  element? " 

Command  unique  software  often  becomes  the  basis 
for  Department  of  the  Army  Standard  Bystems  and  is 
also  frequently  exported  to  other  locations.  To 
the  extent  that  standard  data  elements  are  used, 
as  shown  in  the  18-12  series  of  Army  Regulations 
(Catalog  of  Standard  Data  Elements  and  Codes), 


interface  conditions  are  quarantecd.  As  a simplistic 
example,  consider  a program  which  has  as  required 
output  military  grades.  Should  "Captain"  be 
expressed  as  "CRT",  "Capt",  "03"  or  "Captain".  To 
the  extent  that  18-12  is  followed,  the  potential  for 
reprogramming  is  avoided.  Obviously,  the  longer  the 
program,  the  more  reprogramming/cost  involved. 
Responses  to  this  question  indicated  that  programmers 
are  not  aware  of  the  18-12  series  of  Army  Regulations 
and  that  designers  of  command  unique  systems  often 
leave  details  of  data  elements  to  the  programmers 
decision.  Not  one  programmer  indicated  that 
reference  was  made  to  formal  publications  when  the 
need  to  determine  a data  element  arose.  Rather, 


a "meaningful  term"  was  used  or  a "whatever  is  logical 
type  decision  was  made.  These  types  of  decisions 
appear  to  be  frequently  made  by  programmers,  as  677 
indicated  that  specifics  were  not  provided  by  designer 
Expressed  in  terms  of  the  designer,  only  335.’  provided 
details.  In  relation  to  the  "Captain"  example  given 
earlier,  the  programmer  might  have  detailed  instruc- 
tions on  data  manipulation,  but  only  broad  guidance 
as  to  input/output  data  element  construction. 

Question  6.  "Who  is  responsible  for  documenta- 
tion?" 


This  question  relates  to  the  specific  area  of 
program  documentation  as  opposed  to  the  broader 
aspect  of  system  documentation.  The  question  was 
asked  in  order  to  determine  the  degree  of  programmer 
independence.  Responses  indicated  that  the  programmer 
is  100%  responsible. 

Question  7.  "Poos  your  software  documentation 
contain  a program  narrative,  comments  throughout  tine 


program , and  a flowchart?" 


This  is  perhaps  the  most  complex  question 
asked  during  the  interviews  and  provoked  the  most 
discussion  of  all  questions.  Accordingly,  detailed 
discussions  of  principles  involved  will  be  provided. 

To  the  portion  of  the  question  concerning  a program 
narrative,  87%  responded  that  a narrative  was  used. 

This  figure  can  be  further  divided  and  indicates  that 
46%  use  a narrative  within  the  program  listing  and 
41%  restrict  narratives  to  the  overall  documentation 
package.  Comments  were  used  by  46%  of  the  programmers, 
while  33%  indicated  that  flowcharts  were  used. 

Although  somewhat  lengthy,  consider  the  following 
example  of  a small  subroutine  coded  in  FORTRAN.  With- 


out comments  or  narrative,  the  code  looks  like: 


30 

SUBROUTINE  ABLE ( I ARRAY, I ROW, ICOL, ICSSEQ , JSORT ) 

31 

DIMENSION  IARRAY( 25,25) , ICSSEQ( 25) , IOUT ( 20) 

32 

NTHRU=IROW— 1 

33 

DO  20  I TIMES =1 ,NTHRU 

34 

IP0INT=I TIMES 

35 

ICARRY=ITIMES 

36 

DO  30  IR=ICARRY, IROW 

37 

DO  40  K0LUMN=1 , I SORT 

38 

ICOLSB=IABS( ICSSEQ (KOLUMN) ) 

39 

IF ( ICSSEQ (KOLUMN) .GT.O)  GO  TO  35 

40 

IF  ( IARRAY( IPOINT, ICOLSB) . LT. IARRAY( IR, ICOLSB) ) 
GO  TO  45 

41 

IF ( IARRAY( IPOINT , ICOLSB ) . EQ . I ARRAY ( IR , ICOLSB ) ) 
GO  TO  40 

42 

GO  TO  30 

43 

35 

IF(IARRAY( IPOINT, ICOLSB) .GT. IARRAY( IR, ICOLSB) ) 
GO  TO  45 

44 

IF (IARRAY( IPOINT, ICOLSB). LT.IARRAY(IR, ICOLSB)) 
GO  TO  30 

45 

40 

CONTINUE 

46 

45 

IP0INT=IR 

47 

30 

CONTINUE 

48 

DO  50  ISWITCH=1 , ICOL 

49 

ISTORE=IARRAY( IPOINT , ISWICH ) 

50 

IARRAY( IPOINT , ISWICH ) =IARRAY( ITIMES , ISWICH ) 

51 

I ARRAY (I TIMES, ISWICH) =IST0RE 

52 

50 

CONTINUE 

53 

20 

CONTINUE 

54 

RETURN 

55 

END 

25 


Although  the  routine  has  but  20  instructions, 
it  is  extremely  difficult  to  decipher  without 
additional  information.  One  can  easily  see  the 
difficulty  facing  a programmer  when  tasked  to  modify 
such  a program.  The  complex  situation  existing  in 
a 2000  instruction  code  sequence  would  require 
tremendous  expenditures  of  time  before  modification 
could  begin.  Now,  consider  the  same  sequence  of 
code  when  comments  are  added: 


30 


31 

32 

33 

34 

35 
3G 
37 


C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 


SUBROUTINE  ABLE ( I ARRAY, IRON, ICOL, ICSSEQ , ISORT ) 

THIS  SUBROUTINE  PERFORMS  THE  ACTUAL.  SORT 
ROUTINE.  THE  COLUMN  SORT  SEQUENCE  DETERMINES 
THE  COLUMNS  TO  BE  SORTED  AS  WELL  AS  THE  SEQUENCE. 
A + INDICATES  ASCENDING  AND  A - DECENDING 
VARIABLE  NAMES 

NTHRU-NUMBER  OF  TIMES  THROUGH  THE  ARRAY 
I TIMES -CONTROLS  MOVEMENT  THROUGH  DATA  TO 
BE  SWITCHED 

IPOINT— BASE  COMPARE  LOCATION 
ICAURY- ' SEARCH ' COMPARE  LOCATION 
ICOLSB-USED  FOR  COLUMN  IDENTIFICATION 

DO  LOOP  20  * * * * * DETERMINES  HOW  MANY  TIMES 
THE  SWITCHING  WILL  OCCUR. 

(NUMBER  OF  ROWS  TO  BE  SWITCHED 

-1) 

DO  LOOP  30*  * * * ^CONTROLS  THE  ROW  SELECTION 

FOR  COMPARISON  WITH  POINTER. 

DO  LOOP  40*  * * * *CONTROLS  THE  COLUMN  BEING 

USED  WITH  THE  COMPARE  SEQUENCE* 

BY  MOVING  THROUGH  THIS  LOOP, 
WITHOUT  ENTERING  FROM  LOOP  30, 

A FURTHER  ATTEMPT  TO  RESOLVE 
EQUAL  SITUATIONS  CAN  BE  MADE. 

DO  LOOP  S0*****G0NTR0L8  THE  ACTUAL  SWITCHING 
OF  ARRAY  ELEMENTS,  AND  DUE 
TO  ITS  LOOP  CAPABILITY,  THE 
ULTIMATE  SWITCHING  OF  ENTIRE 
ROWS  WITHIN  THE  ARRAY. 

DIMENSION  IARRAY( 25,25) , ICSSEQ ( 25 ) , IOUT( 20) 

NTHRU-IROW-1 

DO  20  ITIMES-l.NTHRU 

IPOINT-ITIMES 

ICARRY-ITIMES 

DO  30  IR-ICARRY.IROW 

DO  40  KOLUMN-1, ISORT 


C INSURE  POSITIVE  NUMBER 


EQ(KOLUMN) ) 


ICOLSB=IABS(IC 


C CHECK  FOR  ASCENDING  ORDER-BRANCH  TO  35  IF 
C POSITIVE 


IF( ICSSEQ(KOLUMN) . GT.O)  go  TO  35 


BRANCH  AS  APPROPRIATE 


C CHECK  VALUE 


IF  ( IARRAY ( IPOINT , ICOLSB ) . LT. I ARRAY ( IR 
ICOLSB) ) CO  TO  45 

IF ( IARRAY ( IPOINT .ICOLSB) . EQ . IARRAY ( IR, 
ICOLSB))  GO  TO  40 
CO  TO  30 


C CHECK  VALUES-BRANCH  AS  APPROPRIATE 


35  IF ( IARRAY( IPOINT , ICOLSD ) . GT . IARRAY ( IR, 

ICOLSB)) CO  TO  45 

IF( IARRAY ( IPOINT , ICOLSB ) . LT . IARRAY ( IR , ICOLSB ) ) 
GO  TO  30 
40  CONTINUE 


C RESET  POINTER 


45  IPOINT=IR 
30  CONTINUE 
C 

C SWITCH  ELEMENT 


48  DO  50  ISWICHcl , ICOL 

49  I STORED  ARRAY  ( IPOINT , ISWICH) 

50  IARRAY( IPOINT, ISWICH) =IARRAY( ITIMES , ISWICH) 

51  I ARRAY ( ITIMES , ISWIC1 1 ) =I5T0RE 

52  50  CONTINUE 

53  20  CONTINUE 

54  RETURN 

55  END 

An  observer  need  not  be  knowledgable  of  FORTRAN 
to  see  that  the  addition  of  comments  has  greatly 
added  to  the  understanding  of  the  subroutine.  By 
looking  at  comments  pertaining  to  the  overall  program 
further  understanding  can  be  achieved.  In  this 
illustration,  such  comments  might  read:  (Comments 
would  appear  in  the  program  listing.) 


c 

C THIS  IS  A FORTRAN  PROGRAM  WHICH  CONTAINS 
C A SUBPROGRAM.  THE  PURPOSE  OF  THE  PROGRAM* 

C THROUGH  USE  OF  THE  SUBROUTINE,  IS  TO  PERFORM 
C A TV/O  DIMENSIONAL,  MULTI-COLUMN  .VARIABLE 
C SEQUENCE  SORT.  IT  ALSO  UTILIZES  VARIABLE 
C ’INPUT  AND  OUTPUT  FORMATS. (THE  PROGRAM  HAS 
C NOT  BEEN  MODIFIED  SINCE  IT  WAS  WRITTEN ) 

C PROGRAM  VARIABLES 

C ALPHA-ALPHANUMERIC  INFORMATION 

C ICSSEQ-COLUMN  SORT  SEQUENCE 

C IN-INPUT  FORMAT 

C IOUT-OUTPUT  FORMAT 

C I ARRAY-ARRAY  FOR  HOLDING  DATA 

C I ROW-NUMBER  OF  ROWS  OF  DATA 

C ICOL-NUMBER  OF  COLUMNS  OF  DATA 

C ISORT-NUMBER  OF  COLUMNS  TO  BE  SORTED 

C 

An  overall  relation  has  now  been  provided.  Again, 
consider  a complex  2000  instruction  sequence  of  code 
and  consider  the  addition  of  a program  narrative: 


PROGRAM  NARRATIVE  DESCRIPTION 
This  is  a Fortran  program,  which  contains  a main  program 
with  a subroutine  call.  It  performs  a two-dimensional , 
multi-column,  variable  sequence  sort,  and  utilizes 
variable  input  and  output  formats.  The  maximum  number 
of  rows  and  columns  to  be  sorted  must  be  equal  to  or 
less  than  25.  In  order  for  the  program  to  function 
properly,  the  following  data  must  be  supplied: 

Number  of  rows  of  data 
Number  of  columns  of  data 
Number  of  columns  to  be  sorted 
Problem  description 

Column  sort  sequence  with  indication  of 
ascending  or  descending 
Input  format  for  data 
Output  format  for  data 

Note:  This  program  is  an  independent  program,  and 

does  not  interface  with  any  system. 
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The  operations  are  as  follow: 

1.  The  number  of  rows  and  the  number  of  columns 
in  the  data  set  is  read,  along  with  the  number 

of  columns  to  be  sorted.  Alphanumeric  information 
describing  the  problem  is  also  read. 

2.  Formats  to  be  used  for  input  and  output 
are  read. 

3.  All  of  the  information  listed  above  is 
printed,  with  appropriate  labelling  information. 

4.  Data  is  read  and  printed  in  its  original 
sequence . 

5.  A subroutine  (Able)  is  used  to  perform  a 
sort  of  the  data,  using  the  "Modified  Cascade 
method. 

6.  Data  is  printed  in  its  sorted  sequence. 

7.  If  additional  data  is  present,  steps  1-6 
are  re-executed 

8.  The  program  terminates  on  an  error  condition 
when  additional  data  is  not  present, 

A programmer  or  analyst  with  basic  FORTRAN  know- 
ledge would  now  have  a much  better  concept  of  program 
logic  and  intent.  To  give  a visual  assist,  a flowchart 
(Figure  1)  can  be  provided.  From  the  above  example, 
it  can  be  seen  that  the  absence  of  either  narrative, 
flowchart,  or  comments  degrades  the  capability  for 
program  maintenance.  The  absence  of  all  three  can 
create  an  impossible  situation. 

Question  8.  "Who  approves  your  finished  docu- 
mentation?" 

Answers  to  this  question  indicate  the  degree 
to  which  documentation  is  reviewed  for  adequacy. 
Opinions  as  to  capabilities  of  those  reviewing  arc 
addressed  in  Question  Nine.  Seventy-three  percent 
responded  that  their  supervisor/ section  chief 


approved  the  documentation.  The  disturbing  fact 
remaining  is  that  27%  indicated  that  no  approval  was 
required. 

Question  9.  "In  your  opinion,  and  based  upon 
your  experience,  have  your  supervisors  been  techni- 
cally capable  of  reviewing  your  work?" 

This  question  is  significant  in  relation  to 
question  eight  and  also  provides  insight  into  the 
independence  of  programmers  working  in  a command 
unique  environment.  Fully  80%  expressed  the  opinion 
that  their  supervisors  were  not  technically  capable 
of  providing  assistance  or  evaluating  work  in  the 
area  of  programming.  This  perception  related  almost 
exclusively  to  senior  supervisors  in  the  grade  of 
E-7,  E-8,  E-9,  and  to  all  officers.  The  inability 
of  senior  enlisted  members  to  deal  with  details 
of  programming  seems  to  stem  from  previous  promotion 
patterns.  Although  not  a specific  interview  question, 
it  seems  that  many  enlisted  supervisors  reached  their 
present  positions  through  the  route  of  machine  operator. 
It  follows  then,  that  their  knowledge  of  programming 
would  be  limited.  Lack  of  officer  capability  seems 
linked  to  the  wide  background  of  those  possessing 
specialty  code  53  (ADP).  This  specialty  code  is 
used  to  identify  officers  possessing  everything  from 
on  job  experience  to  doctorial  degrees.  Come  may 
well  be  qualified  to  deal  with  programming,  but  the 
perception  is  that  most  are  not. 

Question  10.  "When  programming,  what  reference 
documents  do  you  use  to  assist  you  should  you  have 
problems? " 

Specific  guidelines  are  available  to  programmers 
in  technical  manuals  published  by  the  U.  S.  Army 
Computer  Systems  Command.  Use  of  these  manuals 
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would  insure  maximum  adherence  to  Army  and  ANSI  stan- 
dards and  would  impact  specifically  upon  the  use  of 
manufacturers  unique  capabilities.  The  important 
factor  being  that  standards  tend  to  insure  software 
compatibility  among  various  hardware  configurations. 
Some  examples  of  manufacturer’s  unique  features 
include  Burrough's  capability  to  index  more  than 
two  fields  and  the  use  of  "vs"  for  designating 
literals.  Conti'Ol  Bata  Corporation  offers  a six 
character  rather  than  a four  character  word  confi  . ora- 
tion, and  IBM's  "Transform"  verb  is  unique.  The 
use  ox'  these  types  of  unique  capability  obviously 
tie  a program  to  specified  hardware  and  require 
expenditures  of  time  and  money  when  hardware  is 
changed.  It  was  found  that  manufacturer's  litera- 
ture was  used  as  the  sole  reference  by  73%  of  the 
programmers , 20%  used  Army  publications,  and  7% 
used  a mix  of  both  Army and  manufacturer  supplied 
documents. 

question  11.  "Do  you  program  for  hardware 
independence?" 

This  question  is  related  directly  to  question 
ten  and  directly  impacts  upon  the  area  of  software 
conversion  cost.  The  fact  that  87%  of  those  inter- 
viewed responded  "no"  indicates  that  programmers 
either  are  not  aware  of,  or  are  not  concerned  with, 
possible  conversion  to  different  hardware  at  a later 
date. 

Question  12.  "Has  any  outside  agency  ever 
checked  your  completed  work." 

In  93%  of  the  responses,  the  answer  was  no. 
Considering  that  work  may  have  been  reviewed  after 
a programmer's  departure,  it  could  be  argued  that 
this  figure  is  high.  However,  only  13b  indicated 
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that  an  outside  agency  (Inspector  dcneral  or  Command 
Management  Information  bystera  Office)  had  over  been 
observed  to  review  documentation.  Indications  are 
that  external  review  a,  encies  simpl \ do  not  have 
the  capability  to  review  documentation  for  adherence 
to  requirements  and  for  adequacy. 

question  13.  "Low  do  you  account  for  time  spent 


This  question  was  designed  to  give  an  insight 
into  how  developmental  costs  are  accumulated  on 
command  unique  software.  Without  an  accurate  account 
ing  of  time,  a large  portion  of  cost  will  not  be 
reflected.  In  turn,  it  becomes  impossible  to  know 
when  Department  of  the  Amy  standards  for  command 
unique  software/ systems  have  been  exceeded.  desnoses 
indicated  that  3 7m  had  no  requirement  or  no  effeotive 
way  to  keep  track  of  programming,  effort  devoted  to 
a particular  program  or  system. 


question  14.  "Are  you  .-ivon  a restrict 
the  j...tximum  allowable  core  size  which  you 
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some  sort  was  given.  Amount  of  core  to  be  used 
varied  and  was  dependent  upon  total  core  available. 
Those  interviewed,  who  reflected  no  restriction, 
indicated  that  core  was  not  a problem  but  that  they 
programmed  to  use  "as  little  core  as  possible".  "hi 
question  is  somewhat  related  to  question  eleven  and 
provides  another  indication  as  to  how  standards  are 


being  observed. 

Question  lb.  "Who 
routines?  If  so,  how?" 


The  use  of  subroutines,  which  break  logical 
sequences  of  code  into  smaller  stand  alone  modules, 
has  several  advajitag.es.  Of  prime  importance  is  the 
use  of  this  technique  to  control  the  size  of  core 
to  be  used.  Ry  using,  subroutines  of  a specified 


size,  lar  e pro  rains  can  be  produced  which  will  run 
on  both  large  and  small  computers.  (By  the  use  of 
"overlaying",  subroutines  are  called  into  the  core 
of  small  machines  only  when  needed.)  Answers  to 
this  question  revealed  that  00‘-  of  pro  rammers  use 
subroutines.  Of  those  using  subroutines,  96Sj  used 
them  for  the  reason  stated  above.  The  remaining 
4%  used  subroutines  only  to  avoid  writing  repetitious 
sections  of  code. 

Question  lb.  "Do  you  have  any  comments  concern- 
in,,  pro,  rain  languages  or  documentation  which  you 
would  like  to  make?" 

As  could  be  expected,  many  comments  were  made. 

I will,  however,  reflect  only  those  which  have 
significance  to  this  paper. 

An  E-5  Programmer — "Internal  documentation 
is  critical,  if  it  isn't  in  the  program  list- 
ing it  won't  be  used.  External  documentation 
can  never  be  trusted  because  no  one  is  sure  it 
is  current." 

An  E-d  COBOL  programmer — "Army  standards  arc 
too  strict.  None  of  the  supervisors  know 
enough  to  determine  when  they  are  met." 

An  K-b  COBOL  programmer — "We  have  a dollar 
cost  which  is  hidden.  It  j tied  directly  to 
poor  documentation." 

An  E-6  supervisor — "Quick  fixes  on  software 
always  occur  under  short  fuses  and  it  seems 
to  be  always  late  at  night.  If  documentation 
was  in  the  program  listing,  the  job  would  be 
easier. " 

An  E-5  programmer — "Once  you've  tried  to 
modify  someone  else's  program,  you  understand 
about  documentation." 
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A ’,.'-3  supervisor:  "Most  bosses  Just  want  the 
program  to  be  placed  in  an  operational  mode. 

They  have  no  concept  of  the  long  range  importance 
of  documentation.  Time  is  not  allocated  for 
documentation.  As  soon  as  a program  is  running., 
it's  on  to  the  next  Job!" 


Chapter  v 
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From  the  evidence  presented  in  this  paper, 
several  conclusions  will  be  made  and  recommendations 
offered.  In  addition,  the  author  recognizes  that 
this  study  is  not  conclusive  and  that  several  areas 
deserve  further  study.  These  areas  will  also  be 
shown.  It  should  be  remembered  that  only  the 
command  unique  environment  has  been  examined. 

Conclusion  1 

High  level  languages  are  available  which 
offer  significant  advantages  to  the  Army.  To 

adapt  such  a language  would  save  programming  time, 
provide  more  thorough  documentation,  and  result  in 
long  term  dollar  savings. 

Recommendation  1 

A more  detailed  analysis  of  savings  to  be 
derived  from  the  use  of  a system  language  should  be 
made.  Supportive  evidence  should  then  be  presented 
to  the  Department  of  Defense  and  approval  authority 
for  use  aggressively  pursued. 

Conclusion  2 

Software  documentation  for  command  unique 
systems  is  being  accomplished  in  a very  haphazard 
manner.  Standards  are  difficult  to  understand, 
incomplete,  and  without  effective  review  or  approval 
authority. 

Recommendation  2 

A more  simplistic  set  of  standards  for  command 
unique  software  should  be  developed.  These  standards 
should  be  published  as  a separate  reference  document 
and  should  recognize  the  limited  resources  generally 
available  where  command  unique  systems  exist.  Specific 
requirements  should  include  mandatory  use  of  comments 
throughout  the  program  listing  and  a goal  of  having 
maximum  documentation  resident  within  the  program 
listing. 
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Recommendation  3 


The  Army  should,  in  recognition  of  inadequate 
technical  skills  existing  in  the  command  unique 
environment,  establish  a central  review  and  approval 
authority  for  software  documentation.  Tills  review 
of  documentation  (revised  per  recommendation  2) 
would  achieve  several  benefits: 

A.  Significant  but  unknown  dollar  savings 
would  accrue  through  reduced  system  maintenance 
cost. 

D.  An  effective  and  practical  method  of 
enforcing  standards  would  exist.  Inspection 
agencies  would  have  only  to  ask  for  certifica- 
tion of  documentation  wrhen  inspecting.  Software 
not  having  a "Certificate  of  Approval"  would 
be  easily  identified.  In  turn,  software 
reviewed  by  a central  agency  would  presumably 
meet  all  standards. 

C.  As  a by  product  of  the  review,  information 
concerning  identification  and  capability  of 
command  unique  systems  could  be  extracted.  A 
truly  accurate  central  library  could  then  be 
established. 

D.  By  including  cost  as  a criteria,  an 
incentive  for  accurate  systems  cost  recording 
would  be  generated. 

E.  The  empahsis  on  documentation,  generated 
by  a central  review,  would  create  an  awareness 

not  now  present  in  the  command  unique  environ- 
ment. 

Recommendation  4 

A review  of  Officers  holding  career  field  53 
specialties  should  be  made.  The  object  of  such  a 


review  would  be  to  determine  the  validity  of 
assignment  to  this  field.  The  wide  variance 
existing  between  high  and  low  degrees  of  technical 
knowledge  is  unfair  both  to  the  Officer  and  to  the 
Army. 

Recommendation  5 

A review  of  software  documentation  and  its 
importance,  as  taught  by  the  Army  School  System, 
should  be  made. 

Recommendation  G 

An  effective  way  of  reflecting  the  true  cost 
of  system  maintenance  should  be  developed.  This 
cost  is  suspected  to  be  high,  but  data  is  not 
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